

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  
  <title>HashiCorp Vault Integration &mdash; Ceph Documentation</title>
  

  
  <link rel="stylesheet" href="../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" />

  
  

  
  

  

  
  <!--[if lt IE 9]>
    <script src="../../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/jquery.js"></script>
        <script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
        <script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/doctools.js"></script>
        <script src="../../_static/sphinx_highlight.js"></script>
    
    <script type="text/javascript" src="../../_static/js/theme.js"></script>

    
    <link rel="index" title="Index" href="../../genindex/" />
    <link rel="search" title="Search" href="../../search/" />
    <link rel="next" title="KMIP Integration" href="../kmip/" />
    <link rel="prev" title="与 OpenStack Barbican 对接" href="../barbican/" /> 
</head>

<body class="wy-body-for-nav">

   
  <header class="top-bar">
    <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../../" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="../">Ceph 对象网关</a></li>
      <li class="breadcrumb-item active">HashiCorp Vault Integration</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../../_sources/radosgw/vault.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
  </header>
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #eee" >
          

          
            <a href="../../" class="icon icon-home"> Ceph
          

          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search/" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../start/">Ceph 简介</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../install/">安装 Ceph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephadm/">Cephadm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rados/">Ceph 存储集群</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephfs/">Ceph 文件系统</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rbd/">Ceph 块设备</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../">Ceph 对象网关</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../frontends/">HTTP 前端</a></li>
<li class="toctree-l2"><a class="reference internal" href="../multisite/">多站配置</a></li>
<li class="toctree-l2"><a class="reference internal" href="../zone-features/">域的功能</a></li>
<li class="toctree-l2"><a class="reference internal" href="../placement/">存储池归置与存储类</a></li>
<li class="toctree-l2"><a class="reference internal" href="../multisite-sync-policy/">多站同步策略配置</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pools/">存储池的配置</a></li>
<li class="toctree-l2"><a class="reference internal" href="../config-ref/">配置参考</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/">管理指南</a></li>
<li class="toctree-l2"><a class="reference internal" href="../account/">用户账户</a></li>
<li class="toctree-l2"><a class="reference internal" href="../s3/">S3 API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../iam/">IAM API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../rgw-cache/">数据缓存和 CDN</a></li>
<li class="toctree-l2"><a class="reference internal" href="../swift/">Swift API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../adminops/">管理操作 API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../api/">Python 接口</a></li>
<li class="toctree-l2"><a class="reference internal" href="../nfs/">通过 NFS 导出</a></li>
<li class="toctree-l2"><a class="reference internal" href="../keystone/">与 OpenStack Keystone 对接</a></li>
<li class="toctree-l2"><a class="reference internal" href="../barbican/">与 OpenStack Barbican 对接</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">与 HashiCorp Vault 对接</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#vault-secrets-engines">Vault secrets engines</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#kv-secrets-engine">KV secrets engine</a></li>
<li class="toctree-l4"><a class="reference internal" href="#transit-secrets-engine">Transit secrets engine</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#vault-authentication">Vault authentication</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#token-policies-for-the-object-gateway">Token policies for the object gateway</a></li>
<li class="toctree-l4"><a class="reference internal" href="#token-authentication">Token authentication</a></li>
<li class="toctree-l4"><a class="reference internal" href="#vault-agent">Vault agent</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#vault-namespaces">Vault namespaces</a></li>
<li class="toctree-l3"><a class="reference internal" href="#create-a-key-in-vault">Create a key in Vault</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#using-the-kv-engine">Using the KV engine</a></li>
<li class="toctree-l4"><a class="reference internal" href="#using-the-transit-engine">Using the Transit engine</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#configure-the-ceph-object-gateway">Configure the Ceph Object Gateway</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#transit-engine-compatibility-support">Transit engine compatibility support</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#upload-object">Upload object</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../kmip/">与 KMIP 对接</a></li>
<li class="toctree-l2"><a class="reference internal" href="../opa/">与 Open Policy Agent 对接</a></li>
<li class="toctree-l2"><a class="reference internal" href="../multitenancy/">多租户</a></li>
<li class="toctree-l2"><a class="reference internal" href="../compression/">压缩</a></li>
<li class="toctree-l2"><a class="reference internal" href="../ldap-auth/">LDAP 认证</a></li>
<li class="toctree-l2"><a class="reference internal" href="../encryption/">服务器端加密</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bucketpolicy/">桶策略</a></li>
<li class="toctree-l2"><a class="reference internal" href="../dynamicresharding/">动态的桶索引重分片</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mfa/">多因子认证</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sync-modules/">同步模块</a></li>
<li class="toctree-l2"><a class="reference internal" href="../notifications/">Bucket Notifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../layout/">RADOS 中的数据布局</a></li>
<li class="toctree-l2"><a class="reference internal" href="../STS/">STS</a></li>
<li class="toctree-l2"><a class="reference internal" href="../STSLite/">STS Lite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../keycloak/">Keycloak</a></li>
<li class="toctree-l2"><a class="reference internal" href="../session-tags/">Session Tags</a></li>
<li class="toctree-l2"><a class="reference internal" href="../role/">Role</a></li>
<li class="toctree-l2"><a class="reference internal" href="../orphans/">Orphan List and Associated Tooliing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../oidc/">OpenID Connect Provider</a></li>
<li class="toctree-l2"><a class="reference internal" href="../troubleshooting/">故障排除</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../man/8/radosgw/">radosgw 手册页</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../man/8/radosgw-admin/">radosgw-admin 手册页</a></li>
<li class="toctree-l2"><a class="reference internal" href="../qat-accel/">使用 QAT 为加密和压缩提速</a></li>
<li class="toctree-l2"><a class="reference internal" href="../s3select/">S3-select</a></li>
<li class="toctree-l2"><a class="reference internal" href="../lua-scripting/">Lua Scripting</a></li>
<li class="toctree-l2"><a class="reference internal" href="../d3n_datacache/">D3N Data Cache</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cloud-transition/">Cloud Transition</a></li>
<li class="toctree-l2"><a class="reference internal" href="../metrics/">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../uadk-accel/">UADK Acceleration for Compression</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bucket_logging/">桶的日志记录</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/">Ceph 管理器守护进程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/dashboard/">Ceph 仪表盘</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../monitoring/">监控概览</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../api/">API 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../architecture/">体系结构</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/developer_guide/">开发者指南</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/internals/">Ceph 内幕</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../governance/">项目管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../foundation/">Ceph 基金会</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../ceph-volume/">ceph-volume</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/general/">Ceph 版本（总目录）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/">Ceph 版本（索引）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../security/">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../hardware-monitoring/">硬件监控</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary/">Ceph 术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../jaegertracing/">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../translation_cn/">中文版翻译资源</a></li>
</ul>

            
          
        </div>
        
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../">Ceph</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
<div id="dev-warning" class="admonition note">
  <p class="first admonition-title">Notice</p>
  <p class="last">This document is for a development version of Ceph.</p>
</div>
  <div id="docubetter" align="right" style="padding: 5px; font-weight: bold;">
    <a href="https://pad.ceph.com/p/Report_Documentation_Bugs">Report a Documentation Bug</a>
  </div>

  
  <section id="hashicorp-vault-integration">
<h1>HashiCorp Vault Integration<a class="headerlink" href="#hashicorp-vault-integration" title="Permalink to this heading"></a></h1>
<p>HashiCorp <a class="reference external" href="https://www.vaultproject.io/docs/">Vault</a> can be used as a secure key management service for
<a class="reference external" href="../encryption">Server-Side Encryption</a> (SSE-KMS).</p>
<p class="ditaa">
<img src="../../_images/ditaa-3dcc17dc9d352417e352d5543e64cd0b5d17049e.png"/>
</p>
<ol class="arabic simple">
<li><p><a class="reference internal" href="#vault-secrets-engines">Vault secrets engines</a></p></li>
<li><p><a class="reference internal" href="#vault-authentication">Vault authentication</a></p></li>
<li><p><a class="reference internal" href="#vault-namespaces">Vault namespaces</a></p></li>
<li><p><a class="reference internal" href="#create-a-key-in-vault">Create a key in Vault</a></p></li>
<li><p><a class="reference internal" href="#configure-the-ceph-object-gateway">Configure the Ceph Object Gateway</a></p></li>
<li><p><a class="reference internal" href="#upload-object">Upload object</a></p></li>
</ol>
<p>Some examples below use the Vault command line utility to interact with
Vault. You may need to set the following environment variable with the correct
address of your Vault server to use this utility:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">VAULT_ADDR</span><span class="o">=</span><span class="s1">&#39;https://vault-server-fqdn:8200&#39;</span>
</pre></div>
</div>
<section id="vault-secrets-engines">
<h2>Vault secrets engines<a class="headerlink" href="#vault-secrets-engines" title="Permalink to this heading"></a></h2>
<p>Vault provides several secrets engines, which can store, generate, and encrypt
data. Currently, the Object Gateway supports:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.vaultproject.io/docs/secrets/kv/">KV secrets engine</a> version 2</p></li>
<li><p><a class="reference external" href="https://www.vaultproject.io/docs/secrets/transit">Transit engine</a></p></li>
</ul>
<section id="kv-secrets-engine">
<h3>KV secrets engine<a class="headerlink" href="#kv-secrets-engine" title="Permalink to this heading"></a></h3>
<p>The KV secrets engine is used to store arbitrary key/value secrets in Vault. To
enable the KV engine version 2 in Vault, use the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vault</span> <span class="n">secrets</span> <span class="n">enable</span> <span class="o">-</span><span class="n">path</span> <span class="n">secret</span> <span class="n">kv</span><span class="o">-</span><span class="n">v2</span>
</pre></div>
</div>
<p>The Object Gateway can be configured to use the KV engine version 2 with the
following setting:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">secret</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">kv</span>
</pre></div>
</div>
</section>
<section id="transit-secrets-engine">
<h3>Transit secrets engine<a class="headerlink" href="#transit-secrets-engine" title="Permalink to this heading"></a></h3>
<p>The transit engine handles cryptographic functions on data in-transit. To enable
it in Vault, use the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vault</span> <span class="n">secrets</span> <span class="n">enable</span> <span class="n">transit</span>
</pre></div>
</div>
<p>The Object Gateway can be configured to use the transit engine with the
following setting:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">secret</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">transit</span>
</pre></div>
</div>
</section>
</section>
<section id="vault-authentication">
<h2>Vault authentication<a class="headerlink" href="#vault-authentication" title="Permalink to this heading"></a></h2>
<p>Vault supports several authentication mechanisms. Currently, the Object
Gateway can be configured to authenticate to Vault using the
<a class="reference external" href="https://www.vaultproject.io/docs/auth/token.html">Token authentication method</a> or a <a class="reference external" href="https://www.vaultproject.io/docs/agent/index.html">Vault agent</a>.</p>
<p>Most tokens in Vault have limited lifetimes and powers.  The only
sort of Vault token that does not have a lifetime are root tokens.
For all other tokens, it is necessary to periodically refresh them,
either by performing initial authentication, or by renewing the token.
Ceph does not have any logic to perform either operation.
The simplest best way to use Vault tokens with ceph is to
also run the Vault agent and have it refresh the token file.
When the Vault agent is used in this mode, file system permissions
can be used to restrict who has the use of tokens.</p>
<p>Instead of having Vault agent refresh a token file, it can be told
to act as a proxy server.  In this mode, Vault will add a token when
necessary and add it to requests passed to it before forwarding them on
to the real server.  Vault agent will still handle token renewal just
as it would when storing a token in the filesystem.  In this mode, it
is necessary to properly secure the network path rgw uses to reach the
Vault agent, such as having the Vault agent listen only to localhost.</p>
<section id="token-policies-for-the-object-gateway">
<h3>Token policies for the object gateway<a class="headerlink" href="#token-policies-for-the-object-gateway" title="Permalink to this heading"></a></h3>
<p>All Vault tokens have powers as specified by the polices attached
to that token.  Multiple policies may be associated with one
token.  You should only use the policies necessary for your
configuration.</p>
<p>When using the kv secret engine with the object gateway:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vault</span> <span class="n">policy</span> <span class="n">write</span> <span class="n">rgw</span><span class="o">-</span><span class="n">kv</span><span class="o">-</span><span class="n">policy</span> <span class="o">-&lt;&lt;</span><span class="n">EOF</span>
  <span class="n">path</span> <span class="s2">&quot;secret/data/*&quot;</span> <span class="p">{</span>
    <span class="n">capabilities</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;read&quot;</span><span class="p">]</span>
  <span class="p">}</span>
<span class="n">EOF</span>
</pre></div>
</div>
<p>When using the transit secret engine with the object gateway:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vault</span> <span class="n">policy</span> <span class="n">write</span> <span class="n">rgw</span><span class="o">-</span><span class="n">transit</span><span class="o">-</span><span class="n">policy</span> <span class="o">-&lt;&lt;</span><span class="n">EOF</span>
  <span class="n">path</span> <span class="s2">&quot;transit/keys/*&quot;</span> <span class="p">{</span>
    <span class="n">capabilities</span> <span class="o">=</span> <span class="p">[</span> <span class="s2">&quot;create&quot;</span><span class="p">,</span> <span class="s2">&quot;update&quot;</span> <span class="p">]</span>
    <span class="n">denied_parameters</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;exportable&quot;</span> <span class="o">=</span> <span class="p">[],</span> <span class="s2">&quot;allow_plaintext_backup&quot;</span> <span class="o">=</span> <span class="p">[]</span> <span class="p">}</span>
  <span class="p">}</span>

  <span class="n">path</span> <span class="s2">&quot;transit/keys/*&quot;</span> <span class="p">{</span>
    <span class="n">capabilities</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;read&quot;</span><span class="p">,</span> <span class="s2">&quot;delete&quot;</span><span class="p">]</span>
  <span class="p">}</span>

  <span class="n">path</span> <span class="s2">&quot;transit/keys/&quot;</span> <span class="p">{</span>
    <span class="n">capabilities</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;list&quot;</span><span class="p">]</span>
  <span class="p">}</span>

  <span class="n">path</span> <span class="s2">&quot;transit/keys/+/rotate&quot;</span> <span class="p">{</span>
    <span class="n">capabilities</span> <span class="o">=</span> <span class="p">[</span> <span class="s2">&quot;update&quot;</span> <span class="p">]</span>
  <span class="p">}</span>

  <span class="n">path</span> <span class="s2">&quot;transit/*&quot;</span> <span class="p">{</span>
    <span class="n">capabilities</span> <span class="o">=</span> <span class="p">[</span> <span class="s2">&quot;update&quot;</span> <span class="p">]</span>
  <span class="p">}</span>
<span class="n">EOF</span>
</pre></div>
</div>
<p>If you had previously used an older version of ceph with the
transit secret engine, you might need the following policy:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vault</span> <span class="n">policy</span> <span class="n">write</span> <span class="n">old</span><span class="o">-</span><span class="n">rgw</span><span class="o">-</span><span class="n">transit</span><span class="o">-</span><span class="n">policy</span> <span class="o">-&lt;&lt;</span><span class="n">EOF</span>
  <span class="n">path</span> <span class="s2">&quot;transit/export/encryption-key/*&quot;</span> <span class="p">{</span>
    <span class="n">capabilities</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;read&quot;</span><span class="p">]</span>
  <span class="p">}</span>
<span class="n">EOF</span>
</pre></div>
</div>
<p>If you are using both sse-kms and sse-s3, then you should point
each to separate containers.  You could either use separate
vault instances, or you could use either separately mounted
transit instances, or different branches under a common transit
point.  If you are not using separate vault instances, you can
use these to point kms and sse-s3 to separate containers:
<code class="docutils literal notranslate"><span class="pre">rgw_crypt_vault_prefix</span></code>
and/or
<code class="docutils literal notranslate"><span class="pre">rgw_crypt_sse_s3_vault_prefix</span></code>.
When granting vault permissions to sse-kms bucket owners, you should
not give them permission to muck around with sse-s3 keys;
only ceph itself should be doing that.</p>
</section>
<section id="token-authentication">
<h3>Token authentication<a class="headerlink" href="#token-authentication" title="Permalink to this heading"></a></h3>
<p>The token authentication method expects a Vault token to be present in a
plaintext file. The Object Gateway can be configured to use token authentication
with the following settings:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">auth</span> <span class="o">=</span> <span class="n">token</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">token</span> <span class="n">file</span> <span class="o">=</span> <span class="o">/</span><span class="n">run</span><span class="o">/.</span><span class="n">rgw</span><span class="o">-</span><span class="n">vault</span><span class="o">-</span><span class="n">token</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">addr</span> <span class="o">=</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">vault</span><span class="o">-</span><span class="n">server</span><span class="o">-</span><span class="n">fqdn</span><span class="p">:</span><span class="mi">8200</span>
</pre></div>
</div>
<p>Adjust these settings to match your configuration.
For security reasons, the token file must be readable by the Object Gateway
only.</p>
</section>
<section id="vault-agent">
<h3>Vault agent<a class="headerlink" href="#vault-agent" title="Permalink to this heading"></a></h3>
<p>The Vault agent is a client daemon that provides authentication to Vault and
manages token renewal and caching. It typically runs on the same host as the
Object Gateway. With a Vault agent, it is possible to use other Vault
authentication mechanism such as AppRole, AWS, Certs, JWT, and Azure.</p>
<p>The Object Gateway can be configured to use a Vault agent with the following
settings:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">auth</span> <span class="o">=</span> <span class="n">agent</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">addr</span> <span class="o">=</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="mf">127.0.0.1</span><span class="p">:</span><span class="mi">8100</span>
</pre></div>
</div>
<p>You might set up vault agent as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vault</span> <span class="n">write</span> <span class="n">auth</span><span class="o">/</span><span class="n">approle</span><span class="o">/</span><span class="n">role</span><span class="o">/</span><span class="n">rgw</span><span class="o">-</span><span class="n">ap</span> \
  <span class="n">token_policies</span><span class="o">=</span><span class="n">rgw</span><span class="o">-</span><span class="n">transit</span><span class="o">-</span><span class="n">policy</span><span class="p">,</span><span class="n">default</span> \
  <span class="n">token_max_ttl</span><span class="o">=</span><span class="mi">60</span><span class="n">m</span>
</pre></div>
</div>
<p>Change the policy here to match your configuration.</p>
<dl class="simple">
<dt>Get the role-id:</dt><dd><dl class="simple">
<dt>vault read auth/approle/role/rgw-ap/role-id -format=json | </dt><dd><p>jq -r .data.role_id</p>
</dd>
</dl>
</dd>
</dl>
<p>Store the output in some file, such as /usr/local/etc/vault/.rgw-ap-role-id</p>
<dl class="simple">
<dt>Get the secret-id:</dt><dd><dl class="simple">
<dt>vault read auth/approle/role/rgw-ap/role-id -format=json | </dt><dd><p>jq -r .data.role_id</p>
</dd>
</dl>
</dd>
</dl>
<p>Store the output in some file, such as /usr/local/etc/vault/.rgw-ap-secret-id</p>
<p>Create configuration for the Vault agent, such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pid_file</span> <span class="o">=</span> <span class="s2">&quot;/run/rgw-vault-agent-pid&quot;</span>
<span class="n">auto_auth</span> <span class="p">{</span>
  <span class="n">method</span> <span class="s2">&quot;AppRole&quot;</span> <span class="p">{</span>
    <span class="n">mount_path</span> <span class="o">=</span> <span class="s2">&quot;auth/approle&quot;</span>
    <span class="n">config</span> <span class="o">=</span> <span class="p">{</span>
      <span class="n">role_id_file_path</span> <span class="o">=</span><span class="s2">&quot;/usr/local/etc/vault/.rgw-ap-role-id&quot;</span>
      <span class="n">secret_id_file_path</span> <span class="o">=</span><span class="s2">&quot;/usr/local/etc/vault/.rgw-ap-secret-id&quot;</span>
      <span class="n">remove_secret_id_file_after_reading</span> <span class="o">=</span><span class="s2">&quot;false&quot;</span>
    <span class="p">}</span>
  <span class="p">}</span>
<span class="p">}</span>
<span class="n">cache</span> <span class="p">{</span>
  <span class="n">use_auto_auth_token</span> <span class="o">=</span> <span class="n">true</span>
<span class="p">}</span>
<span class="n">listener</span> <span class="s2">&quot;tcp&quot;</span> <span class="p">{</span>
  <span class="n">address</span> <span class="o">=</span> <span class="s2">&quot;127.0.0.1:8100&quot;</span>
  <span class="n">tls_disable</span> <span class="o">=</span> <span class="n">true</span>
<span class="p">}</span>
<span class="n">vault</span> <span class="p">{</span>
  <span class="n">address</span> <span class="o">=</span> <span class="s2">&quot;https://vault-server-fqdn:8200&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Then use systemctl or another method of your choice to run
a persistent daemon with the following arguments:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">vault</span> <span class="n">agent</span> <span class="o">-</span><span class="n">config</span><span class="o">=/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">vault</span><span class="o">/</span><span class="n">rgw</span><span class="o">-</span><span class="n">agent</span><span class="o">.</span><span class="n">hcl</span>
</pre></div>
</div>
<p>Once the vault agent is running, you should find it listening
to port 8100 on localhost, and you should be able to interact
with it using the vault command.</p>
</section>
</section>
<section id="vault-namespaces">
<h2>Vault namespaces<a class="headerlink" href="#vault-namespaces" title="Permalink to this heading"></a></h2>
<p>In the Enterprise version, Vault supports the concept of <a class="reference external" href="https://www.vaultproject.io/docs/enterprise/namespaces/index.html">namespaces</a>, which
allows centralized management for teams within an organization while ensuring
that those teams operate within isolated environments known as tenants.</p>
<p>The Object Gateway can be configured to access Vault within a particular
namespace using the following configuration setting:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">namespace</span> <span class="o">=</span> <span class="n">tenant1</span>
</pre></div>
</div>
</section>
<section id="create-a-key-in-vault">
<h2>Create a key in Vault<a class="headerlink" href="#create-a-key-in-vault" title="Permalink to this heading"></a></h2>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Keys for server-side encryption must be 256-bit long and base-64
encoded.</p>
</div>
<section id="using-the-kv-engine">
<h3>Using the KV engine<a class="headerlink" href="#using-the-kv-engine" title="Permalink to this heading"></a></h3>
<p>A key for server-side encryption can be created in the KV version 2 engine using
the command line utility, as in the following example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>vault kv put secret/myproject/mybucketkey key=$(openssl rand -base64 32)
</pre></div>
</div>
<p>Sample output:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">======</span> <span class="n">Metadata</span> <span class="o">======</span>
<span class="n">Key</span>              <span class="n">Value</span>
<span class="o">---</span>              <span class="o">-----</span>
<span class="n">created_time</span>     <span class="mi">2019</span><span class="o">-</span><span class="mi">08</span><span class="o">-</span><span class="mi">29</span><span class="n">T17</span><span class="p">:</span><span class="mi">01</span><span class="p">:</span><span class="mf">09.095824999</span><span class="n">Z</span>
<span class="n">deletion_time</span>    <span class="n">n</span><span class="o">/</span><span class="n">a</span>
<span class="n">destroyed</span>        <span class="n">false</span>
<span class="n">version</span>          <span class="mi">1</span>
</pre></div>
</div>
<p>Note that in the KV secrets engine, secrets are stored as key-value pairs, and
the Gateway expects the key name to be <code class="docutils literal notranslate"><span class="pre">key</span></code>, i.e. the secret must be in the
form <code class="docutils literal notranslate"><span class="pre">key=&lt;secret</span> <span class="pre">key&gt;</span></code>.</p>
</section>
<section id="using-the-transit-engine">
<h3>Using the Transit engine<a class="headerlink" href="#using-the-transit-engine" title="Permalink to this heading"></a></h3>
<p>Keys created for use with the Transit engine should no longer be marked
exportable.  They can be created with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vault</span> <span class="n">write</span> <span class="o">-</span><span class="n">f</span> <span class="n">transit</span><span class="o">/</span><span class="n">keys</span><span class="o">/</span><span class="n">mybucketkey</span>
</pre></div>
</div>
<p>The command above creates a keyring, which contains a key of type
<code class="docutils literal notranslate"><span class="pre">aes256-gcm96</span></code> by default. To verify that the key was correctly created, use
the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vault</span> <span class="n">read</span> <span class="n">transit</span><span class="o">/</span><span class="n">keys</span><span class="o">/</span><span class="n">mybucketkey</span>
</pre></div>
</div>
<p>Sample output:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Key</span>     <span class="n">Value</span>
<span class="o">---</span>     <span class="o">-----</span>
<span class="n">derived</span>                   <span class="n">false</span>
<span class="n">exportable</span>                <span class="n">false</span>
<span class="n">name</span>                      <span class="n">mybucketkey</span>
<span class="nb">type</span>                      <span class="n">aes256</span><span class="o">-</span><span class="n">gcm96</span>
</pre></div>
</div>
</section>
</section>
<section id="configure-the-ceph-object-gateway">
<h2>Configure the Ceph Object Gateway<a class="headerlink" href="#configure-the-ceph-object-gateway" title="Permalink to this heading"></a></h2>
<p>Edit the Ceph configuration file to enable Vault as a KMS backend for
server-side encryption:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">s3</span> <span class="n">kms</span> <span class="n">backend</span> <span class="o">=</span> <span class="n">vault</span>
</pre></div>
</div>
<p>Choose the Vault authentication method, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">auth</span> <span class="o">=</span> <span class="n">token</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">token</span> <span class="n">file</span> <span class="o">=</span> <span class="o">/</span><span class="n">run</span><span class="o">/.</span><span class="n">rgw</span><span class="o">-</span><span class="n">vault</span><span class="o">-</span><span class="n">token</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">addr</span> <span class="o">=</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">vault</span><span class="o">-</span><span class="n">server</span><span class="o">-</span><span class="n">fqdn</span><span class="p">:</span><span class="mi">8200</span>
</pre></div>
</div>
<p>Or:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">auth</span> <span class="o">=</span> <span class="n">agent</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">addr</span> <span class="o">=</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span><span class="mi">8100</span>
</pre></div>
</div>
<p>Choose the secrets engine:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">secret</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">kv</span>
</pre></div>
</div>
<p>Or:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">secret</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">transit</span>
</pre></div>
</div>
<p>Optionally, set the Vault namespace where encryption keys will be fetched from:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">namespace</span> <span class="o">=</span> <span class="n">tenant1</span>
</pre></div>
</div>
<p>Finally, the URLs where the Gateway will retrieve encryption keys from Vault can
be restricted by setting a path prefix. For instance, the Gateway can be
restricted to fetch KV keys as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">prefix</span> <span class="o">=</span> <span class="o">/</span><span class="n">v1</span><span class="o">/</span><span class="n">secret</span><span class="o">/</span><span class="n">data</span>
</pre></div>
</div>
<p>Or, when using the transit secret engine:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">prefix</span> <span class="o">=</span> <span class="o">/</span><span class="n">v1</span><span class="o">/</span><span class="n">transit</span>
</pre></div>
</div>
<p>In the example above, the Gateway would only fetch transit encryption keys under
<code class="docutils literal notranslate"><span class="pre">https://vault-server:8200/v1/transit</span></code>.</p>
<p>You can use custom ssl certs to authenticate with vault with help of
following options:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">verify</span> <span class="n">ssl</span> <span class="o">=</span> <span class="n">true</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">ssl</span> <span class="n">cacert</span> <span class="o">=</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">ceph</span><span class="o">/</span><span class="n">vault</span><span class="o">.</span><span class="n">ca</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">ssl</span> <span class="n">clientcert</span> <span class="o">=</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">ceph</span><span class="o">/</span><span class="n">vault</span><span class="o">.</span><span class="n">crt</span>
<span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">ssl</span> <span class="n">clientkey</span> <span class="o">=</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">ceph</span><span class="o">/</span><span class="n">vault</span><span class="o">.</span><span class="n">key</span>
</pre></div>
</div>
<p>where vault.ca is CA certificate and vault.key/vault.crt are private key and ssl
certificate generated for RGW to access the vault server. It highly recommended to
set this option true, setting false is very dangerous and need to avoid since this
runs in very secured environments.</p>
<section id="transit-engine-compatibility-support">
<h3>Transit engine compatibility support<a class="headerlink" href="#transit-engine-compatibility-support" title="Permalink to this heading"></a></h3>
<p>The transit engine has compatibility support for previous
versions of ceph, which used the transit engine as a simple key store.</p>
<p>There is a “compat” option which can be given to the transit
engine to configure the compatibility support,</p>
<p>To entirely disable backwards support, use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">secret</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">transit</span> <span class="n">compat</span><span class="o">=</span><span class="mi">0</span>
</pre></div>
</div>
<p>This will be the default in future versions. and is safe to use
for new installs using the current version.</p>
<p>This is the normal default with the current version:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">secret</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">transit</span> <span class="n">compat</span><span class="o">=</span><span class="mi">1</span>
</pre></div>
</div>
<p>This enables the new engine for newly created objects,
but still allows the old engine to be used for old objects.
In order to access old and new objects, the vault token given
to ceph must have both the old and new transit policies.</p>
<p>To force use of only the old engine, use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rgw</span> <span class="n">crypt</span> <span class="n">vault</span> <span class="n">secret</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">transit</span> <span class="n">compat</span><span class="o">=</span><span class="mi">2</span>
</pre></div>
</div>
<p>This mode is automatically selected if the vault prefix
ends in export/encryption-key, which was the previously
documented setting.</p>
</section>
</section>
<section id="upload-object">
<h2>Upload object<a class="headerlink" href="#upload-object" title="Permalink to this heading"></a></h2>
<p>When uploading an object to the Gateway, provide the SSE key ID in the request.
As an example, for the kv engine, using the AWS command-line client:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">aws</span> <span class="o">--</span><span class="n">endpoint</span><span class="o">=</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">radosgw</span><span class="p">:</span><span class="mi">8000</span> <span class="n">s3</span> <span class="n">cp</span> <span class="n">plaintext</span><span class="o">.</span><span class="n">txt</span> <span class="n">s3</span><span class="p">:</span><span class="o">//</span><span class="n">mybucket</span><span class="o">/</span><span class="n">encrypted</span><span class="o">.</span><span class="n">txt</span> <span class="o">--</span><span class="n">sse</span><span class="o">=</span><span class="n">aws</span><span class="p">:</span><span class="n">kms</span> <span class="o">--</span><span class="n">sse</span><span class="o">-</span><span class="n">kms</span><span class="o">-</span><span class="n">key</span><span class="o">-</span><span class="nb">id</span> <span class="n">myproject</span><span class="o">/</span><span class="n">mybucketkey</span>
</pre></div>
</div>
<p>As an example, for the transit engine (new flavor), using the AWS command-line client:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">aws</span> <span class="o">--</span><span class="n">endpoint</span><span class="o">=</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">radosgw</span><span class="p">:</span><span class="mi">8000</span> <span class="n">s3</span> <span class="n">cp</span> <span class="n">plaintext</span><span class="o">.</span><span class="n">txt</span> <span class="n">s3</span><span class="p">:</span><span class="o">//</span><span class="n">mybucket</span><span class="o">/</span><span class="n">encrypted</span><span class="o">.</span><span class="n">txt</span> <span class="o">--</span><span class="n">sse</span><span class="o">=</span><span class="n">aws</span><span class="p">:</span><span class="n">kms</span> <span class="o">--</span><span class="n">sse</span><span class="o">-</span><span class="n">kms</span><span class="o">-</span><span class="n">key</span><span class="o">-</span><span class="nb">id</span> <span class="n">mybucketkey</span>
</pre></div>
</div>
<p>The Object Gateway will fetch the key from Vault, encrypt the object and store
it in the bucket. Any request to download the object will make the Gateway
automatically retrieve the correspondent key from Vault and decrypt the object.</p>
<p>Note that the secret will be fetched from Vault using a URL constructed by
concatenating the base address (<code class="docutils literal notranslate"><span class="pre">rgw</span> <span class="pre">crypt</span> <span class="pre">vault</span> <span class="pre">addr</span></code>), the (optional)
URL prefix (<code class="docutils literal notranslate"><span class="pre">rgw</span> <span class="pre">crypt</span> <span class="pre">vault</span> <span class="pre">prefix</span></code>), and finally the key ID.</p>
<p>In the kv engine example above, the Gateway would fetch the secret from:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">vaultserver</span><span class="p">:</span><span class="mi">8200</span><span class="o">/</span><span class="n">v1</span><span class="o">/</span><span class="n">secret</span><span class="o">/</span><span class="n">data</span><span class="o">/</span><span class="n">myproject</span><span class="o">/</span><span class="n">mybucketkey</span>
</pre></div>
</div>
<p>In the transit engine example above, the Gateway would encrypt the secret using this key:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">vaultserver</span><span class="p">:</span><span class="mi">8200</span><span class="o">/</span><span class="n">v1</span><span class="o">/</span><span class="n">transit</span><span class="o">/</span><span class="n">mybucketkey</span>
</pre></div>
</div>
</section>
</section>



<div id="support-the-ceph-foundation" class="admonition note">
  <p class="first admonition-title">Brought to you by the Ceph Foundation</p>
  <p class="last">The Ceph Documentation is a community resource funded and hosted by the non-profit <a href="https://ceph.io/en/foundation/">Ceph Foundation</a>. If you would like to support this and our other efforts, please consider <a href="https://ceph.io/en/foundation/join/">joining now</a>.</p>
</div>


           </div>
           
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="../barbican/" class="btn btn-neutral float-left" title="与 OpenStack Barbican 对接" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="../kmip/" class="btn btn-neutral float-right" title="KMIP Integration" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2016, Ceph authors and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).</p>
  </div>

   

</footer>
        </div>
      </div>

    </section>

  </div>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>